メインコンテンツまでスキップ

無害化リクエスト

ファイルを SHIELDEX サーバーに送信して無害化 (CDR) を要求する API です。

備考

Important Notes

  • Encoding: すべてのテキストデータはUTF-8でエンコードされる必要があります。
  • Callback: コールバック URL はresult.callbackURLフィールドに設定し、無害化完了後に結果を受け取ることができます。
  • Job ID Length: 最大36文字まで許可されており、超過した場合は有効性検査に失敗します。
  • Authentication : Authorization: Bearer <API-KEY>ヘッダーで連携システムを識別します。APIキーはウェブコンソール → ポリシー → 連携システムポリシーで発行できます。

1. API 概要​

1.1 API リスト​

無害化リクエストは同期および非同期方式で提供されます。

方式MethodAPI説明
非同期POST/v5/cdrリクエストを受け付けてjobIDを返します。無害化結果は結果照会APIまたはCallbackで確認します。
同期POST/v5/cdr-sync無害化が完了した後、最終結果を返します。

Base URL

http://{IP または ドメイン}:{PORT}
項目内容
基本ポート8060(環境に応じて80ポートで構成される場合があります)
エンコーディングUTF-8

1.2 連携方式 (request.type)​

ファイル送信方法をリクエスト専門のrequest.typeで選択します。

項目uploadshared
ファイルの送信リクエスト専門(JSON)とファイルをmultipart/form-dataと一緒に送信リクエスト専門(JSON)のみ送信
事前準備HTTP 通信だけ可能であれば連携両側サーバー間共有フォルダー(NFS)構成必要
結果ファイルGET /v5/download/{jobID}SD_OUTフォルダーまたはGET /v5/download/{jobID}

2. 認証およびアクセス制御​

すべてのリクエストはAuthorizationヘッダーにAPIキーをBearerトークン形式で含めて呼び出します。

Authorization: Bearer <API-KEY>

2.1 API キー認証​

項目内容
伝達位置HTTP Request Header Authorization
発行場所SHIELDEX ウェブコンソール > ポリシー > 連携システムポリシー画面で発行および照会可能

2.2 認証失敗応答​

状況HTTP Status応答メッセージ
API Key 無効401 UnauthorizedThe API Key is invalid. Please verify the API Key.
連動システム未存在401 UnauthorizedThe associated system was not found for this API Key.

3. 無害化リクエスト​

3.1 API 情報​

# 非同期
POST /v5/cdr
POST /v5/cdr/{jobID}

# 同期
POST /v5/cdr-sync
POST /v5/cdr-sync/{jobID}

3.2 HTTP フォーム送信方式 API​

Request Path Parameter

Field

Type

Required

Description

jobID

String

N

  • 무해화 작업 1건의 고유 식별자. 결과 조회·파일 다운로드에 동일하게 사용합니다. 미입력 시 서버가 자동 생성하여 응답에 담아 반환합니다.

  • 최대 36자 · 중복 불가 · 예)202308034b5a9049b9a73

Request Parts (multipart/form-data)

Part

Type

Required

Description

data

JSON

Y

  • 무해화 요청 전문 (요청자 정보 · 파일 정보 · 결과 통지 방법)

  • Content-Type application/json

file

File

Y

  • 무해화 대상 파일 본체.

  • 파일명은 fileinfo.filename 과 동일

Request Data JSON Structure

{
  "request": {
    "type": "upload",
    "id": "BATCH-20260818-001"
  },
  "userinfo": {
    "id": "user001",
    "name": "홍길동",
    "department": "개발팀",
    "dutyname": "책임연구원"
  },
  "fileinfo": {
    "filename": "2026_사업계획.hwp"
  },
  "result": {
    "callbackURL": "https://your-callback-url.com/callback"
  }
}

Request Data Fields

FieldTypeRequiredDescription
request.typeString==Y==ファイル転送方式 - ==upload==
request.idStringN作業グループ ID. いくつかjobIDを一つの作業としてまとめる上位識別子であり、最大36文字です。
userinfo.idString==Y==リクエストユーザーのユニーク識別ID. ログ追跡とユーザー別ポリシー適用の基準値です。
userinfo.nameStringNユーザー名
userinfo.departmentStringNユーザー部門名
userinfo.dutynameStringNユーザーの職位・職名
fileinfo.filenameString==Y==無害化対象ファイル名(拡張子を含む). multipartfileのファイル名と同じである必要があります。
result.callbackURLStringN無害化処理結果がcallbackの場合に使用（該当URLに「無害化結果」全文送信）

REQUEST Sample

同期方式はリクエストURLを/v5/cdr-syncに変更し、それ以外のリクエスト形式は同じです。

curl -X POST "http://{IP}:8060/v5/cdr" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "request": {
      "type": "upload",
      "id": "BATCH-20260818-001"
    },
    "userinfo": {
      "id": "user001",
      "name": "홍길동",
      "department": "개발팀",
      "dutyname": "책임연구원"
    },
    "fileinfo": {
      "filename": "test.pdf"
    },
    "result": {
      "callbackURL": "https://your-callback-url.com/callback"
    }
  };type=application/json' \
  -F "file=@/path/to/test.pdf"

RESPONSE — 受け付け成功 (200 OK)

非同期方式はリクエストを受け取った後jobIDを返します。

{
  "code": 0,
  "msg": "success",
  "jobID": "test-job-001"
}

RESPONSE — 無害化結果 (200 OK)

同期方式は無害化が完了した後、最終結果を返します。

{
  "jobID": "test-job-001",
  "code": 0,
  "detailCode": 0,
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료",
  "msg": "success"
}

3.3 フォルダー共有方式 API​

Request Path Parameter

Field

Type

Required

Description

jobID

String

N

  • 무해화 작업 1건의 고유 식별자. 결과 조회·파일 다운로드에 동일하게 사용합니다. 미입력 시 서버가 자동 생성하여 응답에 담아 반환합니다.

  • 최대 36자 · 중복 불가 · 예)202308034b5a9049b9a73

Request Parts (multipart/form-data)

Part

Type

Required

Description

data

JSON

Y

  • 무해화 요청 전문 (요청자 정보 · 파일 정보 · 결과 통지 방법)

  • Content-Type application/json

file

File

N

  • shared 방식은 전송하지 않습니다.

Request Data JSON Structure

{
  "request": {
    "type": "shared",
    "id": "260622guid12345"
  },
  "userinfo": {
    "id": "user001",
    "name": "홍길동",
    "department": "개발팀",
    "dutyname": "책임연구원"
  },
  "fileinfo": {
    "filename": "57dac8bb-5324-11f1-939c-23ad1125b146.xlsx",
    "subDir": "/subPath1/subPath2/subPath3"
  },
  "result": {
    "callbackURL": "https://your-callback-url.com/callback"
  }
}

Request Data Fields

FieldTypeRequiredDescription
request.typeString==Y==ファイル転送方式 - ==shared==
request.idStringN作業グループ ID. いくつかjobIDを一つの作業としてまとめる上位識別子であり、最大36文字です。
userinfo.idString==Y==リクエストユーザーのユニーク識別ID. ログ追跡とユーザー別ポリシー適用の基準値です。
userinfo.nameStringNユーザー名
userinfo.departmentStringNユーザー部門名
userinfo.dutynameStringNユーザーの職位・職名
fileinfo.filenameString==Y==無害化対象ファイル名(拡張子を含む)。==重複しないファイル名必須==
fileinfo.subDirStringN“フォルダ共有方式”を使用する場合、オプション値として使用できます。 subDir値を使用する場合、無害化リクエスト時にjobID値の伝達が必須です。 - POST /v5/cdr/=={jobID}==
result.callbackURLStringN無害化処理結果がcallbackの場合に使用（該当URLに「無害化結果」全文送信）

REQUEST Sample

ファイルをSD_INにコピーした後fileパートなしで専門のみを送信します。

同期方式はリクエストURLを/v5/cdr-syncに変更し、それ以外のリクエスト形式は同じです。

curl -X POST "http://{IP}:8060/v5/cdr" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: multipart/form-data" \
  -F 'data={
    "request": { "type": "shared" },
    "userinfo": { "id": "user001" },
    "fileinfo": { "filename": "57dac8bb-5324-11f1-939c-23ad1125b146.xlsx", "subDir": "/subPath1/subPath2/subPath3" }
  };type=application/json'

RESPONSE — 受け付け成功 (200 OK)

非同期方式はリクエストを受け取った後jobIDを返します。

{
  "code": 0,
  "msg": "success",
  "jobID": "test-job-001"
}

RESPONSE — 無害化結果 (200 OK)

同期方式は無害化が完了した後、最終結果を返します。

{
  "jobID": "test-job-001",
  "code": 0,
  "detailCode": 0,
  "logReason": 200000,
  "logReasonMsg": "파일 재구성 완료",
  "msg": "success"
}